home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.3 / Interp.3 < prev    next >
Text File  |  1995-07-25  |  9KB  |  199 lines
  1.  
  2.  
  3.  
  4.      TTTTccccllll____IIIInnnntttteeeerrrrpppp((((3333))))                TTTTccccllll (((( ))))                TTTTccccllll____IIIInnnntttteeeerrrrpppp((((3333))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           Tcl_Interp - client-visible fields of interpreter structures
  12.  
  13.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.           ####iiiinnnncccclllluuuuddddeeee <<<<ttttccccllll....hhhh>>>>
  15.  
  16.           typedef struct {
  17.                char *_r_e_s_u_l_t;
  18.                Tcl_FreeProc *_f_r_e_e_P_r_o_c;
  19.                int _e_r_r_o_r_L_i_n_e;
  20.           } Tcl_Interp;
  21.  
  22.           typedef void Tcl_FreeProc(char *_b_l_o_c_k_P_t_r);
  23.      _________________________________________________________________
  24.  
  25.  
  26.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  27.           The  TTTTccccllll____CCCCrrrreeeeaaaatttteeeeIIIInnnntttteeeerrrrpppp  procedure  returns  a  pointer  to  a
  28.           Tcl_Interp  structure.   This  pointer  is  then passed into
  29.           other Tcl procedures to process commands in the  interpreter
  30.           and   perform   other   operations   on   the   interpreter.
  31.           Interpreter structures contain many  many  fields  that  are
  32.           used by Tcl, but only three that may be accessed by clients:
  33.           _r_e_s_u_l_t, _f_r_e_e_P_r_o_c, and _e_r_r_o_r_L_i_n_e.
  34.  
  35.           The _r_e_s_u_l_t and _f_r_e_e_P_r_o_c fields are used to return results or
  36.           error  messages from commands.  This information is returned
  37.           by command procedures back to TTTTccccllll____EEEEvvvvaaaallll, and by TTTTccccllll____EEEEvvvvaaaallll back
  38.           to  its callers.  The _r_e_s_u_l_t field points to the string that
  39.           represents the result or error  message,  and  the  _f_r_e_e_P_r_o_c
  40.           field  tells  how  to  dispose of the storage for the string
  41.           when it isn't needed anymore.  The easiest way  for  command
  42.           procedures  to manipulate these fields is to call procedures
  43.           like TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt or TTTTccccllll____AAAAppppppppeeeennnnddddRRRReeeessssuuuulllltttt;  they will hide  all
  44.           the  details  of managing the fields.  The description below
  45.           is for those procedures that manipulate the fields directly.
  46.  
  47.           Whenever a command procedure returns, it  must  ensure  that
  48.           the  _r_e_s_u_l_t  field  of  its interpreter points to the string
  49.           being returned by the command.  The _r_e_s_u_l_t field must always
  50.           point  to  a valid string.  If a command wishes to return no
  51.           result then _i_n_t_e_r_p->_r_e_s_u_l_t should point to an empty  string.
  52.           Normally,  results  are  assumed to be statically allocated,
  53.           which means that the contents will  not  change  before  the
  54.           next time TTTTccccllll____EEEEvvvvaaaallll is called or some other command procedure
  55.           is invoked.  In this case, the _f_r_e_e_P_r_o_c field must be  zero.
  56.           Alternatively,  a command procedure may dynamically allocate
  57.           its return value (e.g. using mmmmaaaalllllllloooocccc) and store a pointer  to
  58.           it  in  _i_n_t_e_r_p->_r_e_s_u_l_t.  In this case, the command procedure
  59.           must also set _i_n_t_e_r_p->_f_r_e_e_P_r_o_c to the address of a procedure
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 7/10/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      TTTTccccllll____IIIInnnntttteeeerrrrpppp((((3333))))                TTTTccccllll (((( ))))                TTTTccccllll____IIIInnnntttteeeerrrrpppp((((3333))))
  71.  
  72.  
  73.  
  74.           that can free the value (usually ffffrrrreeeeeeee).  If _i_n_t_e_r_p->_f_r_e_e_P_r_o_c
  75.           is non-zero, then Tcl will call _f_r_e_e_P_r_o_c to free  the  space
  76.           pointed  to  by  _i_n_t_e_r_p->_r_e_s_u_l_t  before  it invokes the next
  77.           command.  If a client  procedure  overwrites  _i_n_t_e_r_p->_r_e_s_u_l_t
  78.           when  _i_n_t_e_r_p->_f_r_e_e_P_r_o_c  is  non-zero, then it is responsible
  79.           for calling _f_r_e_e_P_r_o_c to free  the  old  _i_n_t_e_r_p->_r_e_s_u_l_t  (the
  80.           TTTTccccllll____FFFFrrrreeeeeeeeRRRReeeessssuuuulllltttt macro should be used for this purpose).
  81.  
  82.           _F_r_e_e_P_r_o_c should have arguments and  result  that  match  the
  83.           TTTTccccllll____FFFFrrrreeeeeeeePPPPrrrroooocccc   declaration  above:   it  receives  a  single
  84.           argument which is a pointer to the result value to free.  In
  85.           most  applications ffffrrrreeeeeeee is the only non-zero value ever used
  86.           for _f_r_e_e_P_r_o_c.  However, an application may store a different
  87.           procedure  address  in _f_r_e_e_P_r_o_c in order to use an alternate
  88.           memory allocator or in order to do other  cleanup  when  the
  89.           result memory is freed.
  90.  
  91.           As part of processing  each  command,  TTTTccccllll____EEEEvvvvaaaallll  initializes
  92.           _i_n_t_e_r_p->_r_e_s_u_l_t  and _i_n_t_e_r_p->_f_r_e_e_P_r_o_c just before calling the
  93.           command procedure for the command.  The _f_r_e_e_P_r_o_c field  will
  94.           be  initialized to zero, and _i_n_t_e_r_p->_r_e_s_u_l_t will point to an
  95.           empty string.  Commands that do not  return  any  value  can
  96.           simply  leave  the  fields  alone.   Furthermore,  the empty
  97.           string pointed to by _r_e_s_u_l_t is actually part of an array  of
  98.           TTTTCCCCLLLL____RRRREEEESSSSUUUULLLLTTTT____SSSSIIIIZZZZEEEE   characters   (approximately  200).   If  a
  99.           command wishes to return a short string, it can simply  copy
  100.           it to the area pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t.  Or, it can use
  101.           the sprintf procedure to generate a short result  string  at
  102.           the location pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t.
  103.  
  104.           It is a general convention in  Tcl-based  applications  that
  105.           the  result of an interpreter is normally in the initialized
  106.           state described in the previous paragraph.  Procedures  that
  107.           manipulate  an  interpreter's  result  (e.g. by returning an
  108.           error) will  generally  assume  that  the  result  has  been
  109.           initialized  when  the  procedure  is  called.   If  such  a
  110.           procedure is to be called after the result has been changed,
  111.           then  TTTTccccllll____RRRReeeesssseeeettttRRRReeeessssuuuulllltttt  should  be  called first to reset the
  112.           result to its initialized state.
  113.  
  114.           The _e_r_r_o_r_L_i_n_e field is valid only after TTTTccccllll____EEEEvvvvaaaallll  returns  a
  115.           TTTTCCCCLLLL____EEEERRRRRRRROOOORRRR  return  code.   In  this  situation the _e_r_r_o_r_L_i_n_e
  116.           field identifies  the  line  number  of  the  command  being
  117.           executed  when  the  error  occurred.   The line numbers are
  118.           relative to the command being executed:  1 means  the  first
  119.           line  of  the command passed to TTTTccccllll____EEEEvvvvaaaallll, 2 means the second
  120.           line, and so on.  The _e_r_r_o_r_L_i_n_e field is typically  used  in
  121.           conjunction  with  TTTTccccllll____AAAAddddddddEEEErrrrrrrroooorrrrIIIInnnnffffoooo  to  report  information
  122.           about  where  an  error  occurred.   _E_r_r_o_r_L_i_n_e  should   not
  123.           normally be modified except by TTTTccccllll____EEEEvvvvaaaallll.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 7/10/95)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      TTTTccccllll____IIIInnnntttteeeerrrrpppp((((3333))))                TTTTccccllll (((( ))))                TTTTccccllll____IIIInnnntttteeeerrrrpppp((((3333))))
  137.  
  138.  
  139.  
  140.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  141.           free, initialized, interpreter, malloc, result
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 7/10/95)
  196.  
  197.  
  198.  
  199.